









Smaller Installerª

An Installer Utility for the Macintosh¨







UserÕs Guide 1.0.2

© 1993 Bill Goodman
All Rights Reserved


June 28, 1993















Contents
Introduction	4
Features	5
Licensing/Distribution	5
Contact Information	6
Smaller Installer Overview	7
Toolkit Contents	7
Description of Distribution Disk Set	7
Building A Disk Set	8
Installer Operation	10
Requirements/Limitations	10
Launching The Installer	10
Main/AltMain Dialog	11
Installing The Files	14
Completion Dialog	15
Installer Hook Procedure	16
Creating The Source Archive	17
Standard Folders	17
System-related Folders	17
Group Folders	18
Examples	19
Customizing The Installer Resources	21
Starter Resources	22
Customizing The Main Dialog	22
Customizing The AltMain Dialog	26
Customizing The Completion Dialog	26
Customizing The File Icons	27
Using An Installer Hook Procedure	28
Functional Description	29
Parameter Block Definition	30
SetTargetVol Function	31
BeginInstall Function	32
EndInstall Function	32
Example Hook Procedures	33
Working With The Builder	34
Requirements/Limitations	34
The Project File	34
Installer Creator Code	34
Set Source Archive	34
Set Resource File	35
Product Name	35
Standard Groups	35
Build QuickTest	35
Build Disk Set	36
License	37
Tips/Caveats	38


.c1.Introduction
Smaller Installer is an installer program created for developers who distribute software, clip art, HyperCard¨ stacks, databases or other information on floppy disks. It provides a way to distribute data in a compressed format to reduce the number of disks required.

Many developers already use self-extracting archives created by Compact Proª for this purpose. Although this is an inexpensive solution, self-extracting archives have several limitations which make them less than ideal for this purpose. Smaller Installer is designed to address some of these limitations. Since Smaller Installer is based on the same compression technology used in Compact Pro, you can get the benefit of Compact ProÕs award-winning compression along with an improved user interface which can be customized to meet your specific requirements.
.c2.Features
¥	Significantly reduces the number of disks shipped. Files are stored in compressed form using Compact Pro which typically reduces file size by 50%. The installer application typically requires less than 30K bytes.
¥	No practical limits on file sizesÑindividual files may be larger than a single floppy disk. Installer automatically splits files across multiple diskettes as needed. Files are recombined Òon the flyÓ without using any additional disk space on the userÕs system.
¥	Installer dialogs and icons may be customized to display your logo and icons. Customized scrolling text may be added to provide help or instructions.
¥	Main window displays the disk space required for installation and the space available on the current volume.
¥	Installation ÒgroupsÓ may be defined to allow the user to install subsets of the distributed files.
¥	Installed files may be directed to special folders on the userÕs disk, e.g. ÒControl PanelsÓ, ÒExtensionsÓ or other system-related folders.
¥	A custom code resource may be executed before and after an installation to perform additional customization functions if necessary.
.c2.Licensing/Distribution
Toolkit. The Smaller Installer toolkit is distributed as a self-extracting archive file named ÒSmaller Installer PackageÓ. This package contains a set of tools for building custom installer programs. These tools are provided at no charge. You may freely copy and distribute this toolkit with the following restrictions:

¥	The toolkit may only be distributed in its original self-extracting format. No partial distributions are allowed. In other words, only the ÒSmaller Installer PackageÓ file may be copied and distributed.
¥	You may not modify the ÒSmaller Installer PackageÓ file in any way.
Installers. The custom installers created by Smaller Installer contain a copyrighted software program which must be licensed for distribution. You may create up to 5 copies of an installer for testing and evaluation purposes. Any other use of these copiesÑincluding both commercial and noncommercial distributionÑis expressly prohibited.

Licenses for distribution of custom installers created by Smaller Installer are available for a one-time fee. This fee authorizes the creation of a specified number of copies based on the following schedule:

	Quantity	License Fee
	1K	$200	Note: Prices are subject to change
	10K	$500	without notice.
	Unlimited	$1,000

Each license covers distribution of a single product. Subsequent releases of the same product do not require additional licenses unless the total number of copies created exceeds the number licensed.

To obtain a distribution license, follow the instructions provided in the file named ÒSI License FormÓ.
.c2.Contact Information
If you require additional information on technical or licensing issues, please write or call:

US Mail:	Cyclos
	PO Box 31417
	San Francisco, CA 94131-0417

Voice:	415-821-1448

E-mail:	CompuServe Ñ 71101,204
	Internet Ñ 71101.204@compuserve.com
	AppleLink Ñ CYCLOS
.c1.Smaller Installer Overview
The Smaller Installer toolkit consists of an installer ÒbuilderÓ application and a set of auxiliary files which are designed to work with the Compact Pro data compression utility. This combination provides a simple way to create a small, customized,  multi-disk installer for your product.
.c2.Toolkit Contents
The Smaller Installer toolkit contains the following items:

SI BuilderÑInstaller Builder application
SI UserÕs GuideÑUserÕs manual (in MS Word format)
SI Release NotesÑDescription of changes in each release
SI License FormÑInstaller distribution license form
Starter ResourcesÑFolder containing starter resources for custom dialogs and icons
Hook Proc ExamplesÑFolder containing files to create example hook procedures
.c2.Description of Distribution Disk Set
The Builder creates a distribution disk set which consists of one or more diskettes of any size.The first disk contains an installer application and an Òinstaller data fileÓ. If additional disks are required, the Builder stores one installer data file on each disk. You may include other files on the first diskÑa ÒRead Me FirstÓ file is common. These files will be ignored by the installer.

Installer Data Files. The installer data files contain your distribution files in a compressed format which is unique to the Smaller Installer. These files cannot be opened by other applications with meaningful results.

Installer. The installer is an application which contains the code required to expand the compressed files in the installer data files and install them on the userÕs machine. It also includes the code used to interact with the user during an installation. The user must open or double-click the installer to start the installation process. The operation of the installer is described more fully in the chapter titled ÒInstaller OperationÓ.

Disk/Installer/Data File Names. You may name the diskettes any way you please as long as the names are unique. Likewise, there are no restrictions on the names you may use for the installer application and the installer data files; however, it is generally a good idea to use unique names for the data files.

Once a disk set has been built, the installer will not work if the disk or data file names are changed. This is due to the installer storing these names internally. To facilitate installations from network servers, the installer will operate properly if the installer application and all data files are stored in the same folder.
.c2.Building A Disk Set
To build a disk set, you must first create a Òsource archiveÓ. If you require customized dialogs or icons, you will also need to create a Òresource fileÓ. Next, you must run the Builder application. It uses the source archive and resource file to create all the files in the disk set. As you run the Builder, it saves various configuration information in a project document. You may save this document in a Òproject fileÓ to simplify subsequent builds of the disk set.



Project File. The project file contains the names and locations of the source archive and resource file as well as various other configuration information used by the Builder. You can create a project file by using the Save or Save As command in the Builder the first time you build a disk set.

Source Archive. The source archive is a Compact Pro archive which contains all the files you wish to distribute. The hierarchical organization and naming of the folders within the source archive specify the rules for installing the files on the userÕs system. These rules are described in the chapter titled ÒCreating The Source ArchiveÓ. Note that the source archive is not actually shipped with the disk setÑit is only used during the build process to define the data to be shipped.

Resource File. The resource file is a standard Macintosh resource file which you can create using a resource editor such as Resorcerer¨ or ResEditª. It contains any customized dialogs or icons which you wish to use in place of the standard dialogs and icons provided by the Builder. The Smaller Installer toolkit includes starter resource files which you may use to create your own customized resources. Additional guidelines for creating installer resources are provided in the chapter titled ÒCustomizing The Installer ResourcesÓ.
.c1.Installer Operation
The installer application performs the function of decompressing the distribution files in the installer data files and installing them on the userÕs system. It has a highly customizable user interface which you may tailor to suit your requirements.
.c2.Requirements/Limitations
The installer requires System 4.2 or higher and a Macintosh Plus or newer (operation with Macintosh 128K/512K/512KE machines is not supported). It is limited to installing a maximum of 1000 files and folders from one distribution disk set. Disk sets may contain no more than 50 disks. Installation on MFS disks is not supported.
.c2.Launching The Installer
The installer must be launched by double-clicking the installer or selecting the installer and using the Open command in the Finderª. The installer purposely inhibits execution when an installer data file is double-clicked. This prevents errors which could be caused by the presence of multiple vendorsÕ installers on the same disk or by multiple versions of one vendorÕs installer on the same disk.



Figure 1: License Dialog

After launching, the installer displays the License Dialog for several seconds before proceeding to the Main Dialog. You specify the name displayed in the License Dialog using the ÒProduct NameÓ command in the Builder.
.c2.Main/AltMain Dialog
The standard version of the Main Dialog is shown in Figure 2. This dialog indicates the target volume. It also shows the disk space required for the installation and the free space available on the target volume. The Drive and Eject buttons may be used to change the target volume. The Install button starts the installation, and the Quit button terminates execution.



Figure 2: Standard Version of Main Dialog

In addition to the items shown here, the Main Dialog contains a number of additional buttons, checkboxes, radio buttons and user items which are not displayed in the standard dialog. You may modify the Main Dialog to make use of these items or to add custom graphics and text of your own. The items in the dialog may be rearranged and resized in a variety of ways.

Figure 3 shows a version of the Main Dialog which has been customized by adding a companyÕs logo and help text. The logo requires the addition of one ÔPICTÕ resource and the scrolling help text requires one ÔTEXTÕ and one ÔstylÕ resource.


Figure 3: Customized Version of Main Dialog

AltMain Dialog. In addition to the Main Dialog, the installer can display an alternate dialog which is functionally similar to the Main Dialog. This dialog is called the AltMain Dialog. The AltMain Dialog may be used for any purpose; however, its most common use is as a ÒCustomizeÓ dialog to allow the user to modify the installation parameters. It can also be used as a separate Help dialog.

All of the items in the AltMain Dialog operate exactly the same as the items in the Main Dialog with two exceptions:

¥	The Install button is changed to an OK button. It performs the same function as the Switch button described below.
¥	The scrolling help text uses different resources so the AltMain Dialog can display scrolling text which is different from the text displayed in the Main Dialog.
Switch Button. The Main and AltMain Dialogs both contain a Switch button. The Switch button dismisses the currently displayed dialog and switches to the alternate dialog (i.e. the Main Dialog switches to the AltMain Dialog and the AltMain Dialog switches to the Main Dialog). In Figure 3, the Switch button has been renamed ÒCustomize...Ó. When the Customize button is clicked in this example, an AltMain Dialog like the one in Figure 4 could be displayed.



Figure 4: AltMain Dialog Configured as a ÒCustomizeÓ Dialog

Group Checkboxes and Radio Buttons. The Main and AltMain Dialogs contain 16 pre-defined checkboxes and 10 radio buttons which may be used to define Òinstallation groupsÓ. Installation groups are subsets of the files in the distribution disk set. By including some of these checkboxes and radio buttons in your dialogs and defining special folders in the source archive, you can provide a way for users to tailor the installation to their own needs. The AltMain Dialog in Figure 4 uses three of the group radio buttons and two of the group checkboxes to provide installation options. Additional information on using installation groups is provided in the ÒGroup FoldersÓ section of the chapter titled ÒCreating The Source ArchiveÓ.

Standard Button. The Standard button sets all the group checkboxes and group radio buttons to a default setting which you define using the ÒStandard GroupsÓ command in the Builder.
.c2.Installing The Files
When the user clicks the Install button, the installer begins expanding the contents of the installer data files and stores the distribution files on the target volume selected by the user. The status area of the Main Dialog changes to display installation progress as in Figure 5.



Figure 5: Main Dialog During File Installation

During the installation process, the installer prompts the user to insert the various distribution disks as needed using the dialog in Figure 6.




Figure 6: Disk Request Dialog

If the installer finds that one of the files in the distribution set already exists on the target volume, it displays the dialog in Figure 7 to allow the user to decide the proper action.



Figure 6: Replace Dialog
.c2.Completion Dialog
After all selected files have been installed, the installer displays a Completion Dialog. The standard dialog is shown in Figure 7.



Figure 7: Standard Version of Completion Dialog

This dialog may be customized by adding text or pictures as demonstrated in Figure 8.



Figure 8: Customized Version of the Completion Dialog

The installer terminates execution when the Completion Dialog is dismissed. Note that the installer does not display this dialog or terminate execution if any of the files were skipped during installation.
.c2.Installer Hook Procedure
You may customize the operation of the installer by including a code resource called an ÒInstaller Hook ProcedureÓ. If you supply a hook procedure, the installer will call it at various points during the installation to allow you to customize the installation process.

A hook procedure may be used to test for the presence of required hardware or software. It can modify the set of files to be installed by enabling or disabling various installation groups. It can also perform various functions after the files have been installedÑsuch as personalizing a newly installed application or deleting unnecessary files from a previous version of the application.

Additional information on installer hook procedures is provided in the chapter titled ÒUsing An Installer Hook ProcedureÓ.
.c1.Creating The Source Archive
The Òsource archiveÓ is a Compact Pro archive which contains all the files you wish to distribute with your custom installer. The hierarchical organization and naming of the folders in the archive determine the way the files will be installed on the userÕs system. This chapter describes the rules for organizing the archive. If you require additional information on using the Compact Pro utility to create the archive, please refer to the Compact Pro UserÕs Guide provided with the Compact Pro package.
.c2.Standard Folders
The installer reproduces the folder hierarchy of the source archive on the userÕs system beginning in the root folder of the target volume selected by the user. Any folders defined in the source archive which do not already exist on the target volume will be created by the installer.
.c2.System-related Folders
The following special folder names have been defined to refer to various system-related folders:

	$SYSTEM			Currently active system folder
	$APPLE_MENU		Apple Menu Items folder
	$CONTROL_PANELS	Control Panels folder
	$EXTENSIONS		Extensions folder
	$PREFERENCES		Preferences folder
	$STARTUP		Startup Items folder

If a folder in the source archive has one of these special names, the contents of that folder will be placed in the specified system-related folder. Any folder hierarchy within the source archive folder will be reproduced inside the system-related folder on the userÕs system.

Under System 7, any system-related folder will automatically be created if it does not already exist. Under System 6, all of these folders are directed to the currently active system folderÑno folders are ever created.

Note that the installer always installs these files in the active system folder even if that folder is not on the same volume as the target volume selected by the user.
.c2.Group Folders
Installation groups allow users to install subsets of the files in the distribution disk set. You define the contents of the groups by creating Ògroup foldersÓ in the source archive. At installation time, the user may select which groups will be installed by clicking on checkboxes and radio buttons which you have defined in the installer dialogs.

The installer supports 26 groups which are designated by the letters A-Z. The first 16 groups (A-P) are associated with checkboxes in the installer dialogs, so they may be selected in any combination. The next five groups (Q-U) are associated with a set of radio buttons, so only one of these may be selected at a time. Likewise, the final five groups (V-Z) are associated with a second set of radio buttons.

A group folder is defined by starting a folder name with a Ô{Ô character. This is followed by one or more letters designating a group. Comment text may be added to a group folder name after a closing Ô}Õ character.

For example, a folder named Ò{A} Color FilesÓ defines a group folder for group A (Color Files is a descriptive comment). The contents of this folder will only be installed if the user selects the group A checkbox. Note that the group folder itself will NOT be created on the target volumeÑonly the contents of the folder will be created.

If more than one group is specified in a group folder name, the folder will be installed if ANY of the groups in the list are selected. For example, the contents of a folder named Ò{ABQ}Ó would be installed if either checkbox A, checkbox B or radio button Q were selected by the user. This provides a logical ORÕing function for installation groups.

A logical ANDÕing function may be obtained by placing one group folder inside another. For example, if a folder named Ò{J}Ó is created inside another folder named Ò{K}Ó, the installer will only install the contents of the first folder if BOTH checkbox J and checkbox K are selected by the user.
.c2.Examples
Example #1. This example shows the list of files in a source archive for an installer which has one installation group. The group A checkbox in the Main Dialog is labeled ÒInstall ExamplesÓ.

	

	Meteor Folder
		Meteor
		Meteor Help
		{A} example files
			Examples Folder
				Example 1
				Example 2
	$PREFERENCES
		Meteor Preferences

This installer will create a folder named ÒMeteor FolderÓ on the target volume and store the ÒMeteorÓ and ÒMeteor HelpÓ files in the folder. It will also store the ÒMeteor PreferencesÓ file in the ÒPreferencesÓ folder inside the userÕs system folder. If the user has checked the ÒInstall ExamplesÓ checkbox, the installer will also create a folder named ÒExamples FolderÓ inside the ÒMeteor FolderÓ. ÒExample 1Ó and ÒExample 2Ó will be stored in the ÒExamples FolderÓ.

Example #2. This example shows how one of two groups can be installed in the same folder. The installer will create a folder named ÒMeteor FolderÓ on the target volume and store the ÒMeteorÓ file in the folder. If the user selects the ÒColorÓ radio button, the installer will add the ÒColor Plug-InÓ file to the Meteor Folder and store the ÒColor ExtensionÓ file in the Extensions folder. If the user selects the ÒB & WÓ radio button, the installer will add the ÒB&W Plug-InÓ file to the Meteor Folder and store the ÒB&W ExtensionÓ file in the Extensions folder.

	

	Meteor Folder
		Meteor
	{Q} color files
		Meteor Folder
			Color Plug-In
		$EXTENSIONS
			Color Extension
	{R} b&w files
		Meteor Folder
			B&W Plug-In
		$EXTENSIONS
			B&W Extension

Note that this organization keeps all of the files associated with a color installation in one place in the source archive and all of the files associated with a black-and-white installation in another. An alternative organization would be:

	Meteor Folder
		Meteor
		{Q} color files
			Color Plug-In
		{R} b&w files
			B&W Plug-In
	$EXTENSIONS
		{Q} color files
			Color Extension
		{R} b&w files
			B&W Extension

Either arrangement is acceptable. The former tends to be easier to maintain if you have a large number of files in an installation group. The latter may be simpler if the installation groups only affect a few files.
.c1.Customizing The Installer Resources
All the customized resources for your custom installer are stored in a single resource file. When the Builder creates an installer, it checks this file to see if you have provided customized versions of any of the standard installer resources. If it finds a customized resource, it replaces the standard installer resource with your customized version. It also copies any other resources youÕve created to the installerÕs resource fork.

Resource IDs. The installer uses resource IDs 1000 and higher to indicate resources which must not be modified. Since these resources are copyrighted, the Smaller Installer distribution license specifically prohibits the modification of any of these resources. To prevent conflicts, you should use IDs below 1000 for all your resources.

Resource Attributes. Except as noted, all resources should be created with none of the resource attributes asserted, i.e. resources should be non-Preloaded, non-Purgeable, un-Locked, un-Protected and non-SysHeap.

General Limitations On Customizing Dialogs. When customizing dialogs, you may generally move, resize and rename any item except where noted in the following sections. You may also add ÔPICTÕ and static text items as desired. Do NOT delete unused dialog items. If you do not use an item, you should move it outside the visible area of the dialog window. Dialog items must not be renumbered, and the dialog window types must not be changed.

Limitation On PICT Size. The installer is preconfigured with the assumption that no PICT resource is larger than 50K. If any of your PICT resources are larger than this, you must manually increase the memory allocation in the SIZE resource of the final installer to reflect the increased requirement.
.c2.Starter Resources
The Smaller Installer toolkit includes the following starter resource files in the ÒStarter ResourcesÓ folder:

Standard Dialogs.rsrcÑStandard dialog resources created by the Builder
Standard Icons.rsrcÑStandard icon resources created by the Builder
Basic Example.rsrcÑExample using a Main Dialog with a PICT containing a company logo
Text/Group Example.rsrcÑExample using a Main Dialog with a help text field and one group checkbox
AltMain Example.rsrcÑExample using an AltMain Dialog as a ÒCustomizeÓ dialog and a customized Completion Dialog
These files may be used as a starting point for creating your own customized dialogs and icons.
.c2.Customizing The Main Dialog
The Main Dialog requires the following resources:

	Type		ID	Attributes	Description
	ÔDLOGÕ	300	Purgeable	Main Dialog template
	ÔDITLÕ	300	Purgeable	Main Dialog item list

Any ÔPICTÕ or ÔICONÕ resources added to this dialog must be purgeable. The visible attribute in the ÔDLOGÕ resource should be FALSE.

Item #1: Install Button. This button initiates the installation process. A bold outline is drawn around this button while the installer is idle.

Item #2: Quit Button. This button terminates execution of the installer.

Item #3: Switch Button. This button dismisses the Main Dialog and displays the AltMain Dialog. If you are not using the AltMain Dialog, you should move this button outside the visible area of the Main Dialog.

Item #4: Standard Button. This button sets the group checkboxes and radio buttons to their default state. If you are not using the group checkboxes and radio buttons in the Main Dialog, you should move this button outside the visible area.

Item #5: Drive Button. This button changes the volume selected for installation.

Item #6: Eject Button. This button unmounts and ejects the currently selected volume.

Item #7: Help User Item. This item specifies the location where the scrolling help text (if any) will be displayed. To define this text, you must create the following resources:

	Type		ID	Attributes	Description
	ÔTEXTÕ	300			Main help text (32K bytes maximum)
	ÔstylÕ		300			Main help style definition (optional)

Do not set the height or width of this rectangle to 0. If you do not use this item, move it outside the dialogÕs visible area and delete the ÔTEXTÕ and ÔstylÕ resources.

Item #8: Status User Item. This item specifies the location of the installerÕs status display area. All visible user items except the Help User Item must be placed inside this rectangle.



Status Display Area User Items

Item #9: Volume Icon User Item. This item specifies the location of the target volume icon. The item is only drawn when the installer is idle.



Item #9: Volume Icon User Item

Item #10: Volume Name User Item. This item specifies the location of the target volume name. If this item is less than 36 pixels wide, the volume name will be centered at the top of the rectangle. If it is 36 or more pixels wide, the volume name will be left justified at the top of the rectangle and clipped to the rectangle boundary. This item is only displayed while the installer is idle.



Item #10: Volume Name User Item

Item #11: Install Prompt User Item. This item specifies the location of the ÒInstall on:Ó string. This item is only displayed while the installer is idle.



Item #11: Install Prompt User Item

Item #12: Space Required User Item. This item specifies the location of the ÒInstallation requires:Ó string. This item is only displayed while the installer is idle.



Item #12: Space Required User Item

Item #13: Space Available User Item. This item specifies the location of the ÒAvailable on volume:Ó string. This item is only displayed while the installer is idle.



Item #13: Space Available User Item

Item #14: Filename User Item. This item specifies the location of the ÒInstalling file:Ó string and the filename string. The filename is inset 12 pixels from the left and displayed at the bottom of the rectangle. This item is only displayed while the installer is installing files.



Item #14: Filename User Item

Item #15: Progress Bar User Item. This item specifies the location of the progress bar and the ÒFiles to install: nnnÓ string. The files-to-install string is centered at the bottom of the rectangle. This item is only displayed while the installer is installing files.



Item #15: Progress Bar User Item

Item #16-31: Group A-P Checkboxes. These checkboxes enable installation groups A through P. The checkbox titles may be changed as desired, but the item numbers must not be modified.

	Item #:	16	17	18	19	20	21	22	23	24	25	26	27	28	29	30	31
	Group:	A	B	C	D	E	F	G	H	I	J	K	L	M	N	O	P

Item #32-36: Group Q-U Radio Buttons. These radio buttons operate as a set and enable installation groups Q through U. The radio button titles may be changed as desired, but the item numbers must not be modified.

	Item #:	32	33	34	35	36
	Group:	Q	R	S	T	U

Item #37-41: Group V-Z Radio Buttons. These radio buttons operate as a set and enable installation groups V through Z. The radio button titles may be changed as desired, but the item numbers must not be modified.

	Item #:	37	38	39	40	41
	Group:	V	W	X	Y	Z
.c2.Customizing The AltMain Dialog
The installer displays the AltMain Dialog when the ÒSwitchÓ button in the Main Dialog is clicked. This dialog requires the following resources:

	Type		ID	Attributes	Description
	ÔDLOGÕ	301	Purgeable	AltMain Dialog template
	ÔDITLÕ	301	Purgeable	AltMain Dialog item list

Any ÔPICTÕ or ÔICONÕ resources added to this dialog must be purgeable. The visible attribute in the ÔDLOGÕ resource should be FALSE.

All items in the AltMain Dialog operate identically to the items in the Main Dialog with the following exceptions.

Item #1: OK Button. This button dismisses the AltMain Dialog and displays the Main Dialog. A bold outline is drawn around this button while the installer is idle. This button replaces the ÒInstallÓ button in the Main Dialog.

Item #7: Help User Item. This item specifies the location where the scrolling help text (if any) will be displayed. To define this text, you must create the following resources:

	Type		ID	Attributes	Description
	ÔTEXTÕ	301			AltMain help text (32K bytes maximum)
	ÔstylÕ		301			AltMain help style definition (optional)

Do not set the height or width of this rectangle to 0. If you do not use this item, move it outside the dialogÕs visible area and delete the ÔTEXTÕ and ÔstylÕ resources.
.c2.Customizing The Completion Dialog
The installer displays the Completion Dialog after all files have been installed. This dialog requires the following resources:

	Type		ID	Attributes	Description
	ÔDLOGÕ	302	Purgeable	Completion Dialog template
	ÔDITLÕ	302	Purgeable	Completion Dialog item list

Any ÔPICTÕ or ÔICONÕ resources added to this dialog must be purgeable.

Item #1: OK Button. This button dismisses the Completion Dialog and terminates execution of the installer.

The installer will dismiss the Completion Dialog if any enabled item is hit. One common configuration is to move the OK button outside the dialog window and fill the screen with a large ÔPICTÕ item. If the ÔPICTÕ item is enabled, the dialog will be dismissed when the user clicks in the ÔPICTÕ or when the RETURN key is pressed.
.c2.Customizing The File Icons
The standard installer includes two sets of iconsÑone set for the installer application and a second set for the installer data files. To replace the standard icons with your own custom icons, follow these steps.

First, select a unique creator code to be used as the signature for your installer. This code MUST be different from the signature used by the standard installer (ÔSIAPÕ), and it MUST be registered with Apple DTS to ensure that it does not conflict with any other applications. Enter this code in the ÒInstaller Creator CodeÓ field of the Builder project document before you build your disk set.

Second, create a set of icon resources and add them to your installer resource file. As a minimum, you must create the following icon resources:

	Type		ID	Attributes	Description
	ÔICN#Õ	200			Application file icon and mask
	ÔICN#Õ	201			Installer data file icon and mask

To support color icons, you must also create these resources:

	Type		ID	Attributes	Description
	Ôicl4Õ		200			Large 4-bit color application file icon
	Ôicl4Õ		201			Large 4-bit color installer data file icon
	Ôicl8Õ		200			Large 8-bit color application file icon
	Ôicl8Õ		201			Large 8-bit color installer data file icon
	Ôics#Õ		200			Small black/white application file icon
	Ôics#Õ		201			Small black/white installer data file icon
	Ôics4Õ		200			Small 4-bit color application file icon
	Ôics4Õ		201			Small 4-bit color installer data file icon
	Ôics8Õ		200			Small 8-bit color application file icon
	Ôics8Õ		201			Small 8-bit color installer data file icon
.c1.Using An Installer Hook Procedure
You may augment the operation of your custom installer by supplying an ÒInstaller Hook ProcedureÓ. A hook procedure is a code resource which is stored in the installerÕs resource fork. The installer calls the hook procedure at startup, whenever the target volume is changed, before the actual installation begins and after all files have been installed. This provides a number of opportunities to  customize the installation process. Some typical uses for a hook procedure are:

¥	Check for specific machine features before allowing installation to proceed, e.g. minimum operating system version
¥	Automatically select the files to install based on specific machine features, e.g. install color files only on systems with color monitors
¥	Personalize an application after it has been successfully installed
¥	Update or remove files from a previous installation of an older version of an application
To create a hook procedure, use an application development system such as MPW or THINK Cª to create a Òcode resourceÓ with the following definition:

	Type		ID	Attributes	Description
	ÔSICRÕ	500			Smaller Installer code resource

Add this resource and any supplemental resources it requires (such as ÔALRTÕs or ÔDITLÕs) to the installer resource file. All resource IDs must be less than 1000, and they must not conflict with any of the predefined resources used by the installer.
.c2.Functional Description
When the installer is launched, it loads the hook procedure code resource into high memory and locks it in place. The hook remains there until the installer terminates.

The hook procedure code resource has a single entry point with the following Pascal definition:

	PROCEDURE SIHookProc	(VAR parmBlkPtr: SIHookParmBlk);

The installer calls this procedure to perform three different functions: SetTargetVol, BeginInstall and EndInstall. These functions and the parameter block are described in the following sections.

Global Variables. Because the installer hook procedure is a code resource, it must use A4-based addressing to access any variables declared ÒglobalÓ in the hook procedure. Since the code resource remains locked the entire time the installer is running, it is safe to assume that the ÒglobalÓ variables will be nonvolatile.

Heap Usage. The installer is preconfigured to reserve 10K of heap space for the hook procedure code resource and any other non-purgeable resources the hook procedure may require. In addition, the hook procedure can always assume that 50K of heap space is available for purgeable resources. This space may also be used for non-purgeable resources as long as they are released before the hook procedure returns to the installer.

If your hook procedure requires additional heap space, you can manually increase the ÔSIZEÕ resource in your custom installer after each build, or you may add a ÔSIZEÕ resource to your resource file to automatically set the memory partition size.
.c2.Parameter Block Definition
The hook procedure parameter block has the following structure:

CONST	{ Function selector }
	siHookSetTargetVol	= 1;	{ Set target volume }
	siHookBeginInstall	= 2;	{ Begin install }
	siHookEndInstall	= 3;	{ End install }

	{ Completion Status }
	siHookComplete	= 0;	{ Install completed without error }
	siHookFileSkipped	= 1;	{ Install completed but some files were
			  skipped }
	siHookAborted	= 2;	{ Install was aborted due to errors or
			  user cancellation }
	{ Result codes }
	siHookNoErr	= 0;	{ No error }
	siHookAbort	= 1;	{ Error - abort installation }

TYPE	SIHookParmBlk	=
	RECORD
	function:	INTEGER;	{ Function selector }
	targetVRefNum:	INTEGER;	{ VRefNum of target volume }
	groupAPFlags:	INTEGER;	{ Group A-P flags (MSB:P -- LSB:A) }
	groupQUSel:	INTEGER;	{ Group Q-U selector (0:Q -- 4:U) }
	groupVZSel:	INTEGER;	{ Group V-Z selector (0:V -- 4:Z) }
	completionSts:	INTEGER;	{ Completion status for EndInstall }
	result:	INTEGER;	{ Returned result }
	END;

ÒfunctionÓ indicates the reason the hook procedure was called.

siHookSetTargetVol	Target volume was initialized due to installer launch or user has changed target volume

siHookBeginInstall	User has clicked INSTALL button

siHookEndInstall	Installation has completed

ÒtargetVRefNumÓ specifies the volume reference number of the target volume selected by the user.

ÒgroupAPFlagsÓ indicates which of the installation groups ÔAÕ through ÔPÕ are selected for installation. Each bit corresponds to a groupÑthe least significant bit corresponds to group ÔAÕ and the most significant bit corresponds to group ÔPÕ. A Ô1Õ in a bit position indicates the group will be installed and a Ô0Õ indicates it will not be installed.

ÒgroupQUSelÓ indicates which one of the installation groups ÔQÕ through ÔUÕ is selected for installation. A value of 0 corresponds to group ÔQÕ and a value of 4 corresponds to group ÔUÕ.
.c2.
ÒgroupVZSelÓ indicates which one of the installation groups ÔVÕ through ÔZÕ is selected for installation. A value of 0 corresponds to group ÔVÕ and a value of 4 corresponds to group ÔZÕ.

ÒcompletionStsÓ indicates the completion status at the end of an installation. It is only valid for the EndInstall function.

 siHookComplete	Installation completed without error and all selected files were installed

siHookFileSkipped	Installation completed but some selected files were skipped

siHookAborted	Installation was aborted due to errors or because the user cancelled

ÒresultÓ is the result code returned by the hook procedure for BeginInstall and EndInstall function calls.

siHookNoErr	No errorÑproceed with installation
siHookAbort	Abort installation
.c2.SetTargetVol Function
Input Parameters:
function	siHookSetTargetVol
targetVRefNum	Target volume reference number
groupAPFlags	Group A-P flags
groupQUSel	Group Q-U selector
groupVZSel	Group V-Z selector

Returned Values:
groupAPFlags	Group A-P flags
groupQUSel	Group Q-U selector
groupVZSel	Group V-Z selector

The installer executes the SetTargetVol function whenever the target volume is changed. This occurs when the initial target volume is selected (at installer launch) and each time the user changes the target volume. The group parameters indicate the groups which are currently selected to be installed. SetTargetVol can modify the groups selected for installation by changing the group parameters before returning.
.c2.BeginInstall Function
Input Parameters:
function	siHookBeginInstall
targetVRefNum	Target volume reference number
groupAPFlags	Group A-P flags
groupQUSel	Group Q-U selector
groupVZSel	Group V-Z selector

Returned Values:
result	Hook result

The installer executes the BeginInstall function when the user clicks the INSTALL button to begin an installation. BeginInstall may force the installation to be aborted by returning ÒsiHookAbortÓ in ÒresultÓ.
.c2.EndInstall Function
Input Parameters:
function	siHookBeginInstall
targetVRefNum	Target volume reference number
groupAPFlags	Group A-P flags
groupQUSel	Group Q-U selector
groupVZSel	Group V-Z selector
completionSts	Completion status

Returned Values:
result	Hook result

The installer executes the EndInstall function whenever an installation completes. ÒcompletionStsÓ is set to indicate the completion status of the installation. EndInstall may force the installation to be aborted by returning ÒsiHookAbortÓ in ÒresultÓ.

If all files were successfully installed, the installer calls EndInstall with ÒcompletionStsÓ set to ÒsiHookCompleteÓ. This call occurs before the installer displays the Completion Dialog, so the hook procedure can still abort the installation if a problem is detected.

If some files were skipped during the installationÑeither due to file errors or due to the user refusing to replace pre-existing filesÑthe installer calls EndInstall with ÒcompletionStsÓ set to ÒsiHookFileSkippedÓ.

If an unrecoverable error occurs or the user stops the installation after the BeginInstall function has been executed, the installer calls EndInstall with ÒcompletionStsÓ set to ÒsiHookAbortedÓ.
.c2.Hook Procedure Examples
The Smaller Installer toolkit includes the source code for two example hook procedures in the ÒHook Proc ExamplesÓ folder.

DemoHook. DemoHook is a hook procedure which displays an alert each time the hook procedure is called. The ÒDemoHookÓ folder contains the following files:

SIHookProc.hÑC source code interface header for hook procedure
DemoHook.cÑC source code for hook procedure
DemoHook.¹ÑTHINK Cª project file
DemoHook.ALRT.rsrcÑResources used by the hook procedure
DemoHook.SICR.rsrcÑCompiled hook procedure code resource

QD32Hook. QD32Hook is a hook procedure which checks that the target machine is running System 6.0.5 or higher. It also enables or disables an installation group to install the 32-bit Quickdraw file if the target machine is not running version 1.2 or higher of Quickdraw. The ÒQD32HookÓ folder contains the following files:

SIHookProc.hÑC source code interface header for hook procedure
QD32Hook.cÑC source code for hook procedure
QD32Hook.¹ÑTHINK Cª project file
QD32Hook.ALRT.rsrcÑResources used by the hook procedure
QD32Hook.SICR.rsrcÑCompiled hook procedure code resource
.c1.Working With The Builder
The SI Builder is an application which creates distribution disk sets. It combines the data from a source archive and an optional resource file to create a custom installer and a set of installer data files.
.c2.Requirements/Limitations
The Builder requires System 7.0 or higher and a Macintosh Plus or newer.
.c2.The Project File
Before you can build an installer, you must specify various configuration information to be used by the Builder. The Builder saves this information in a ÒprojectÓ document.

To create a new project document, use the New command in the File menu. You may save the project document for future builds by using the Save or Save As commands in the File menu. By convention, project files are named with a Ò.projÓ extension; however, any name is acceptable. 
.c2.Installer Creator Code
The ÒInstaller Creator CodeÓ field defines the 4 character creator code which will be used to build the disk set. This creator code is assigned to the installer application and installer data files created by the Builder. It is also used to create the bundle resources in the installer application.

The default value for this code is ÔSIAPÕ. If you do not require custom icons for your installer, you should use the standard creator code. If you plan to add custom icons, you must select a different creator code and enter it here. Note that this code must be registered with Apple DTS to ensure that it does not conflict with any existing or future applications.
.c2.Set Source Archive
Use the ÒSet Source ArchiveÓ button to specify the Compact Pro source archive used to build your disk set. The source archive must contain only one segment and it must not be self-extracting. For best results, the source archive should be stored on a hard disk.
.c2.Set Resource File
Use the ÒSet Resource FileÓ button to specify the name of a resource file containing your customized installer resources. This file is optional.
.c2.Product Name
Use the ÒProduct NameÓ button to specify the name of your product. This name will be displayed in the ÒLicensed for:Ó field of the License Dialog each time the installer is launched. The Builder allows up to 255 characters for the product name; however, only a single line is displayed in the License Dialog.

Note: This name is defined at the time you pay your license fee. Since it cannot be changed for future releases, you should not include a version number as part of the name.
.c2.Standard Groups
Use the ÒStandard GroupsÓ button to set the default group configuration for the installer. The installerÕs group checkboxes and group radio buttons will be set to this configuration each time it is launched. They will also be set to this configuration whenever the user clicks on the ÒStandardÓ button in the installerÕs Main Dialog or AltMain Dialog.
.c2.Build QuickTest
Use the ÒBuild QuickTestÓ button to create a QuickTest installer. The Builder will create a special test version of your installer called a ÒQuickTest InstallerÓ. QuickTest installers access your source archive directly rather than using a set of installer data files. As a result, you can rapidly build and test a QuickTest installer without creating a disk set. This can save significant development time. Note, however, that QuickTest installers will not work on any system except the one containing the source archive. This makes them unsuitable for final distribution.
.c2.Build Disk Set
Use the ÒBuild Disk SetÓ button to create a complete set of distribution disks. Before you create a disk set, you should prepare a disk to be used as the first disk in the set. First, give the disk an appropriate name (you will NOT be able to change the name later). Next, remove any files which you do not want included in the final distributionÑthe Builder will not delete any files on this disk. If you want to include other files on this disk (e.g. a ÒRead MeÓ file) you should add them now since the Builder will typically fill this disk completely full. Finally, click the ÒBuild Disk SetÓ button to start the build process.



Figure 9: Build Disk Set Dialog

The Builder will display the dialog in Figure 9. Use the disk pop-up menu to select the first disk of the set. You may specify the names of the installer application and the first installer data file in this dialog.

When you click the ÒBuildÓ button, the Builder will add an installer application and an installer data file to this disk. When the disk is full, the Builder will prompt for additional disks as needed.

WARNING: ALL ADDITIONAL DISKS ARE AUTOMATICALLY ERASED BY THE BUILDER BEFORE USE.

Updating Disk Sets. If you use the Build Disk Set command on an existing disk set, the Builder checks the modification date of your source archive. If the archive has not been changed since the last build, the Builder will give you the option of ÒUpdatingÓ the installer on the disk set. During an update, the Builder attempts to save time by replacing only the installer application in your disk set without regenerating all the installer data files.

Since the installer is typically located on a full disk, an update may fail if the new version of your installer is significantly larger than the current version. If this happens, you may have to rebuild the entire disk set.
.c2.License
When you order a license for Smaller Installer, you receive a license number for your product. Use the ÒLicenseÓ command in the File menu to enter your license number in your project file, then rebuild your distribution disk set. This will remove the demonstration dialog which is displayed by unlicensed installers.
.c1.Tips/Caveats
1) You should rebuild the desktop file on each of your distribution disks before shipping. If you do not rebuild the desktop files, the icons for the installer and installer data files may not be displayed properly. Furthermore, users running System 6 may see alerts stating that the disks are damaged and require minor repair. For best results, you should rebuild the desktop files under System 7.

	To rebuild the desktop file for a floppy disk, insert the disk in the floppy drive while holding the COMMAND and OPTION keys.

2)	To ensure each installer data file has been initialized by the Finder, you should open the root folder for each floppy. If the files are not initialized, the view mode may change when loaded on a different system.

3)	The installation process will look better if you close the root folder of all disks except the first in a disk set. This will prevent the Finder from zooming open the window on each disk as it is loaded.

4)	New applications which are installed in closed folders will not be registered in the FinderÕs desktop database until the folder containing the application is manually opened by the user. Any document belonging to the application will appear with a generic icon until the application is registered. For best results, you should direct the user to open the applicationÕs folder as soon as possible.

5)	It is generally a good idea to place all installed files in one folder which the user can easily move to a different destination if desired. If you have help text, it is a good idea to indicate the name of the folder to avoid possible conflicts with any folders the user may already have installed.

6)	If possible, give a list of the files that will be installed and summarize any other modifications the installer will make. This helps power users avoid problems and makes everyone more comfortable with the installation process.

7)	Adding a Ôvers[1]Õ resource to your resource file will allow you to provide a version number and copyright information in the installerÕs Get Info window.

8)	You will typically save space by using object-oriented PICTs rather than bit-mapped PICTs in your resource file; however, be careful not to use unusual fonts in your PICTs since these will display poorly on systems which do not have the fonts installed.

9)	Some virus checking programs will complain when the installer creates or modifies an application. To avoid confusion, it is probably best to add a note to your help text advising users to turn off virus protection programs before starting an installation.

